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Foreword 



This Technical Specification has been produced by the 3 r Generation Partnership Project (3 GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

x the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 16 of a multi-part deliverable covering the 3 r Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OS A); Parlay X Web Services, as identified 
below: 



Parti 


"Common" 


Part 2 


"Third party call" 


Part 3 


"Call Notification" 


Part 4 


"Short Messaging" 


Part 5 


"Multimedia Messaging" 


Part 6 


"Payment" 


Part 7 


"Account management" 


Part 8 


"Terminal Status" 


Part 9 


"Terminal location" 


Part 1( 


3: "Call handling" 


Parti 


1: "Audio call" 


Part l: 


2: "Multimedia conference" 


Parti 


3: "Address list management" 


Part h 


\\ "Presence" 


Part 1. 


5: "Message Broadcast" 


Parti 


6: "Geocoding" 


Part 1' 


7: "Application driven Quality of Service (QoS)" 


Parti 


B: "Device Capabilities and Configuration" 


Part 1 ( 


5: "Multimedia streaming control" 


Part 2( 


3: "Multimedia multicast session management" 


Part 2 


1: "Content management" 


Part 2: 


2: "Policy" 
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1 Scope 

The present document is Part 16 of the Stage 3 Parlay X Web Services specification for Open Service Access (OSA). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Geocoding Web Service aspects of the interface. All aspects of the Geocoding Web 
Service are defined here, these being: 

• Name spaces 

• Sequence diagrams 

• Data definitions 

• Interface specification plus detailed method descriptions 

• Fault definitions 

• Service policies 

• WSDL Description of the interfaces 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 
Maintenance of up to 3GPP Rel-8 and new OSA Stage 1, 2 and 3 work beyond Rel-9 was moved to OMA in June 2008. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22.127: "Service requirement for the Open Services Access (OSA); Stage 1". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] 3 GPP TS 22.101: "Service aspects; Service principles". 

[5] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X web services; Part 1: Common". 

[6] 3GPP TS 29.199-9: "Open Service Access (OSA); Parlay X web services; Part 9: Terminal 

location" . 
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Definitions and abbreviations 



3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [5] and the following 
apply. 

address: set of strings that represent an address information for a geographical place 

It consists of the country, state, district, city, street, house number and zip/postal code. In this specification, the address 

means a location address except where otherwise noted. 

coordinates: latitude, longitude pair that identifies a point on the Earth's surface 

geocoding: transformation a description of a address, such as a place name, street address or postal code, into a 
normalized description of the location with a geographical coordinates 

location: specific set of coordinates 

reverse geocoding: transformation a given location into a normalized description of address 

terminal number: string of decimal digits that terminal is uniquely indicated and located 

NOTE: Address is a name that is used in both Geocoding SCF and Terminal Location SCF. The former uses 
address in the customary sense of a location address, while the latter uses it in the sense of a terminal 
identifier represented as a URI string. So terminal number is a better name for what Parlay X Terminal 
Location calls address, and address as Geocoding SCF typically define it. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [5], 3GPP TS 29.199-9 [6] and 
the following apply: 

GMLC Gateway Mobile Location Center 

MLP Mobile Location Protocol 

MMS Multimedia Message 

MPC Mobile Positioning Center 

OMA Open Mobile Alliance 

OpenLS Open Location Services 

URI Uniform Resource Identifier 

XML Extensible Markup Language 



Detailed service description 



Where the Parlay X Terminal Location Web Service provides access to the geographical coordinates at which a 
terminal is located, the Geocoding Web Service provides access to an additional level of refinement, allowing the 
service developer to work with actual location addresses and the like: 

• Request the location address of a terminal number. 

• Request the location address of a group of terminals. 

• Request the distance of a terminal from a specific location address. 

When a request is made on behalf of a group of terminals, the response may be a full or partial set of results. This 
allows the service to provide results based on a number of criteria, including number of terminals for which the request 
is made and amount of time required to retrieve the information. This allows the requestor to initiate additional requests 
for those terminals for which information was not provided. 
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Figure 4.1 shows the Geocoding Web Service architecture composed of Parlay X Application, Parlay X Gateway, 
Parlay Gateway, GMLC/MPC, Addressing server. OMA/MLP is used between Parlay X Gateway and GMLC/MPC and 
OpenLS/XML is used between Parlay X Gateway and Addressing server. 

In the getAddressOfTerminal and getAddressOfTerminalForGroup operations, if subscriber asks someone's address or 
group addresses, Parlay X Application calls the Geocoding Web Service. Parlay X gateway gets the geographical 
coordinates of terminal number from GMLC/MPC and then feeds the retrieved geographical coordinates to addressing 
server. Finally it gets the location address. 

In the getTerminalDistanceFromAddress operation, the subscriber asks for the distance of a terminal from a specific 
address; the Parlay X Application calls the Geocoding Web Service. The Parlay X gateway gets the geographical 
coordinates of the address from an addressing server. The Parlay X gateway gets the geographical coordinates of the 
terminal from GMLC/MPC. Finally it computes the distance between the two sets of geographical coordinates. 



Parlay X 
Application 



Parlay X 
Application 



Parlay X API « 



SOAP 



SOAP 



Geocoding Web Service 



Parlay X Gateway 



Parlay/OS A API, 



Mobility 



Parlay Gateway 




.OpenLS/XML 



GMLC 
/MPC 



Addressing 
Server 




Figure 4.1 : Geocoding Web Service architecture 
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5 Namespaces 

The Geocoding interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/geocoding/terminal_address/v4_0 
The data types are defined in the namespace: 

http://www.csapi.org/schema/parlayx/geocoding/v4_0 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema 
(3GPP TS 29.199-1 [5]). The use of the name 'xsd' is not semantically significant. 
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6 Sequence diagrams 

6.1 Get address of terminal 

Pattern: Request / Response. 

For an application to determine the address of terminal device, it provides a terminal number and desired accuracy, and 
receives the location address for the device requested. 



:Application 



:Geocodinq Web Service 



Request address of terminal 



Addresslnfo 



0* 



"0 



< 

Retrieve address 
of terminal 



.n 



Figure 6.1 : Get address of terminal operation 



ETSI 



3GPP TS 29.199-16 version 9.0.0 Release 9 



11 



ETSI TS 129 199-16 V9.0.0 (2010-01) 



6.2 Get address of terminal for group 

Pattern: Request / Response. 

For an application to determine the address of a set of terminal devices, it provides an array of terminal numbers, and 
receives the location addresses for the set of devices requested. 



:Application 



:Geocodinq Web Service 



Request address of termina 



for group 



< ' 

Retrieve address of 
terminal for group 



D* 



Address Data 



J 



Figure 6.2: Get address of terminal for group operation 

6.3 Get terminal distance from address 

Pattern: Request / Response. 

For an application to determine the distance from terminal to address, it provides a terminal number and address, and 
receives the distance between location of terminal and address. 



:Application 



:Geocodinq Web Service 



Request terminal distance 
from address 



distance 



(f- 



<r 



I 



<" 



Retrieve location 
of terminal 

Retrieve location 
of address 



.n 



Calculate the distance 
between the location of 
terminal and address 



Figure 6.3: Get terminal distance from address operation 
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7 XML Schema data type definition 

7.1 Accuracy values 

Two accuracy values used in three operations are referred to the 3GPP TS 29.199-9 [6]. The "requested accuracy" is the 
desired accuracy for the terminal location that will be used to generate the address and the 'acceptable accuracy' sets a 
lower bound on accuracy. 



7.2 



Addresslnfo structure 



Data structure of location address composed of country, state, district, city, street, house number, additional 
information, and zip/postal code. 



Name 


Type 


Optional 


Description 


country 


xsd :string 


Yes 


The country is identified by the ISO 3166 code 


state 


xsd :string 


Yes 


National subdivision name (e.g. state, province) 


district 


xsd :string 


Yes 


District name 


city 


xsd :string 


Yes 


City or township name 


street 


xsd :string 


Yes 


Street name 


houseNumber 


xsd :string 


Yes 


House number 


additionallnfo 


xsd :string 


Yes 


Additional location information 


code 


xsd :string 


Yes 


Zip/Postal code 



7.3 AddressData structure 

Data structure containing terminal number and address information for a geographic place. 



Name 


Type 


Optional 


Description 


terminalNumber 


xsd :anyURI 


No 


URI of the terminal for which address information is being requested. 


currentAddress 


Addresslnfo 


No 


Address of terminal, composed of country, state, city, street, house 
number, additional information, and zip/postal code. 



7.4 DelayTolerance enumeration 

Enumeration of the delay tolerance items that forms part of the address or terminal number request. 



Enumeration 



Description 



NoDelay 



The server should immediately return any result estimate that it currently has. If no estimate is available, 
the server shall return the failure indication and may optionally initiate procedures to obtain a result 
estimate (e.g. to be available for a later request). 



LowDelay 



Fulfilment of the response time requirement takes precedence over fulfilment of the accuracy requirement. 
The server shall return any current result estimate with minimum delay. The server shall attempt to fulfill 
any accuracy requirement, but in doing so shall not add any additional delay (i.e. a quick response with 
lower accuracy is more desirable than waiting for a more accurate response). 



DelayTolerantFulfilment of the accuracy requirement takes precedence over fulfilment of the response time requirement. 
If necessary, the server should delay providing a response until the accuracy requirement of the requesting 
application is met. The server shall obtain a current result with regard to fulfilling the accuracy requirement 
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8 



Web service interface definition 



8.1 



Interface: TerminalAddress 



Request the address of a terminal, addresses of a group of terminals, and the distance from a terminal to a specific 
address. 

8.1 .1 Operation: getAddressOfTerminal 

This operation retrieves address information for a single terminal. Requested Accuracy is the desired accuracy for the 
terminal location that will be used to generate the address. Acceptable Accuracy sets a lower bound on accuracy. If 
RequestedAccuracy is not possible, a PolicyException POL0230 is returned. If the accuracy is not within the limit set 
by AcceptableAccuracy, no address information is returned. Instead, a ServiceException(SVC0200) is returned. The 
URI provided is for a single terminal, not a group URL If a group URI is provided, a PolicyException POL0006 is 
returned. 

If tolerance is indicated this affects the priority of accuracy, response time and maximum estimate age. 



8.1.1.1 



Input message: getAddressOfTerminalRequest 



Part name 


Part type 


Optional 


Description 


requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting the information. 

The application invokes this operation on behalf of this entity. 

However, it should NOT be assumed that the application has 

authenticated the requester. 

If this part is not present, the requesting entity is the 

application itself. 


terminalNumber 


xsd :anyURI 


No 


URI of the terminal for which address information is being 
requested. 


requestedAccuracy 


xsd:int 


No 


Accuracy of terminal location on which returned address will 
be based. 


acceptableAccuracy 


xsd:int 


No 


Accuracy of terminal location that is acceptable for determining 
the returned address. 


maximumAge 


common:TimeMetric 


Yes 


Maximum acceptable age, in seconds, of the address 
information that is returned. 


responseTime 


common:TimeMetric 


Yes 


Indicates the maximum time that the application can accept to 
wait for a response. 


tolerance 


DelayTolerance 


No 


Indicates the priority of response time versus accuracy. 



8.1.1.2 



Output message: getAddressOfTerminalResponse 



Part name 


Part type 


Optional 


Description 


result 


Address Info 


No 


Address of the terminal for which address information was requested. 



8.1 .1 .3 Referenced Faults 

ServiceException from 3GPP TS 29.199-1 [5]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0200: Accuracy out of limit. 

• SVC0370: No valid terminal number(s). 

PolicyException from 3GPP TS 29.199-1 [5]: 
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• POL0001: Policy error. 

• POL0002: Privacy error. 

• POL0006: Groups not allowed. 

• POL0230: Requested accuracy not supported. 
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8.1 .2 Operation: getAddressOfTerminalForGroup 

This operation retrieves address information for one or more terminals or groups of terminals. Requested Accuracy is the 
accuracy of terminal location used to generate addresses. AcceptableAccuracy sets a lower bound on that accuracy. If 
RequestedAccuracy is not possible, a PolicyException POL0230 is returned. If the accuracy is not within the limit set 
by AcceptableAccuracy, then the address data will contain a ServiceError (SVC0200). 

If tolerance is indicated this affects the priority of accuracy, response time and maximum estimate age. 



8.1.2.1 



Input message: getAddressOfTerminalForGroupRequest 



Part name 


Part type 


Optional 


Description 


requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting the information. 
The application invokes this operation on behalf of this entity. 
However, it should NOT be assumed that the application has 
authenticated the requester. If this part is not present, the 
requesting entity is the application itself. 


terminalNumbers 


xsd :anyURI 
[1... unbounded] 


No 


List of URIs, including group URIs, of the terminal for which 
address information is being requested. 


requestedAccuracy 


xsd:int 


No 


Accuracy of terminal location on which returned address will 
be based. 


acceptableAccuracy 


xsd:int 


No 


Accuracy of terminal location that is acceptable for determining 
the returned address. 


maximumAge 


common:TimeMetric 


Yes 


Maximum acceptable age, in seconds, of the address 
information that is returned. 


responseTime 


common:TimeMetric 


Yes 


Indicates the maximum time that the application can accept to 
wait for a response. 


tolerance 


DelayTolerance 


No 


Indicates the priority of response time versus accuracy. 



8.1.2.2 



Output message: getAddressOfTerminalForGroupResponse 



Part name 


Part type 


Optional 


Description 


result 


AddressData [1 ...unbounded] 


No 


Addresses of the terminals for which address information was 
requested. 



8.1.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [5]: 



SVC0001 - Service error. 

SVC0002 - Invalid input value. 

SVC0006 - Invalid group. 

S VC0200 - Accuracy out of limit. 

SVC0370 - No valid terminal number(s). 



PolicyException from 3GPP TS 29.199-1 [5]: 



POL0001 - Policy error. 
POL0002 - Privacy error. 
POL0006 - Groups not allowed. 
POL0007 - Nested groups not allowed. 
POL0230 - Requested accuracy not supported. 
POL0350 - Too many terminal numbers. 
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8.1 .3 Operation: GetTerminalDistanceFromAddress 

This operation is intended to determine the distance of a terminal from an address. The URI provided is for a single 
terminal, not a group URI. If a group URI is provided, a PolicyException will be returned to the application. 



8.1.3.1 



Input message: GetTerminalDistanceFromAddressRequest 



Part name 


Part type 


Optional 


Description 


requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting the information. 
The application invokes this operation on behalf of this entity. 
However, it should NOT be assumed that the application has 
authenticated the requester. If this part is not present, the requesting 
entity is the application itself. 


terminalNumber 


xsd:anyURI 


No 


URI of the terminal for which distance information is being requested. 


address 


Addresslnfo 


No 


Address of the location from which to measure 



8.1.3.2 



Output message: GetTerminalDistanceFromAddressResponse 



Part name 


Part type 


Optional 


Description 


result 


xsd:int 


No 


Distance in meters from the terminal to the location address 



8.1.3.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0370: No valid terminal number(s). 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 

• POL0002: Privacy error. 

• POL0006: Groups not allowed. 
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9.1 

9.1.1 



9.2 
9.2.1 



Fault definitions 

Fault: ServiceException 
SVC0200: Accuracy out of limit. 



Name 


Description 


Message Id 


SVC0200 


Text 


Accuracy of location is not within acceptable limit. 


Variables 


None 



9.1 .2 SVC0370: No valid terminal number(s) 



Name 


Description 


Messageld 


SVC0370 


Text 


No valid terminal number(s) provided in message part %1 


Variables 


%1 - message part 



Fault: PolicyException 

POL0230: Requested accuracy not supported 



Name 


Description 


Message Id 


POL0230 


Text 


Requested accuracy is not supported. 


Variables 


None 



9.2.2 POL0350: Too many terminal numbers 



Name 


Description 


Messageld 


POL0350 


Text 


Too many terminal numbers specified in message part %1 


Variables 


%1 - message part 



10 Service policies 

Service policies for this service. 



Name 


Type 


Description 


MinimumAcceptableAccuracy 


xsd:int 


Minimum value for acceptable accuracy 


GroupSupport 


xsd:boolean 


Groups URIs may be used 


NestedGroupSupport 


xsd:boolean 


Are nested groups supported in group definitions 
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Annex A (normative): 
WSDL for Geocoding 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [5] and is 
contained in text files; 

• parlayx_geocoding_terminal_address_interf ace_4_0 . wsdl 

• parlayx_geocoding_terminal_address_service_4_0.wsdl 

• parlayx_geocoding_types_4_0.xsd 
which accompany the present document. 

The WSDL files have been verified using the following files: 

• 16_wsdl2Java_axis-l_4.bat 

• 1 6_wsdl2Java_axis2- 1_4_1 .bat 
which accompany the present document. 
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Annex C (informative): 

Description of Parlay X Web Services Part 16: Geocoding 

for 3GPP2 cdma2000 networks 

This annex is intended to define the OSA Parlay X Web Services Stage 3 interface definitions and it provides the 
complete OSA specifications. It is an extension of OSA Parlay X Web Services specifications capabilities to enable 
operation in cdma2000 systems environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 
architecture defined in: 

[1] 3GPP2 X.S001 1-D: 'cdma2000 Wireless IP Network Standard ", Version 1.1 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 3.0 

[3] 3GPP2 X.S0013-A: "All-IP Core Network Multimedia Domain" 

These requirements are expressed as additions to and/or exclusions from the 3GPP specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3 GPP 

OSA specifications. 



C.1 General Exceptions 



The terms 3GPP and UMTS are not applicable for the cdma2000 family of standards. Nevertheless these terms are used 
(3GPP TR 21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions 
or exclusions required. 

CAMEL mappings are not applicable for cdma2000 systems. 



C.2 Specific Exceptions 
C.2.1 Clause 1: Scope 

There are no additions or exclusions. 

C.2.2 Clause 2: References 

There are no additions or exclusions. 

C.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

C.2. 4 Clause 4: Detailed service description 

There are no additions or exclusions. 

C.2. 5 Clause 5: Namespaces 

There are no additions or exclusions. 
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C.2.6 Clause 6: Sequence diagrams 

There are no additions or exclusions. 

C.2.7 Clause 7: XML Schema data type definition 

There are no additions or exclusions. 

C.2.8 Clause 8: Web Service interface definition 

There are no additions or exclusions. 

C.2.9 Clause 9: Fault definitions 

There are no additions or exclusions. 

C.2.10 Clause 10: Service policies 

There are no additions or exclusions. 

C.2.1 1 Annex A (normative): WSDL for Geocoding 

There are no additions or exclusions. 
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Annex D (informative): 
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